<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>File Framework (GNU Compiler Collection (GCC) Internals)</title>

<meta name="description" content="File Framework (GNU Compiler Collection (GCC) Internals)">
<meta name="keywords" content="File Framework (GNU Compiler Collection (GCC) Internals)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Option-Index.html" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Assembler-Format.html" rel="up" title="Assembler Format">
<link href="Data-Output.html" rel="next" title="Data Output">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>


</head>

<body lang="en">
<div class="subsection-level-extent" id="File-Framework">
<div class="nav-panel">
<p>
Next: <a href="Data-Output.html" accesskey="n" rel="next">Output of Data</a>, Up: <a href="Assembler-Format.html" accesskey="u" rel="up">Defining the Output Assembler Language</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="The-Overall-Framework-of-an-Assembler-File"><span>18.20.1 The Overall Framework of an Assembler File<a class="copiable-link" href="#The-Overall-Framework-of-an-Assembler-File"> &para;</a></span></h4>
<a class="index-entry-id" id="index-assembler-format"></a>
<a class="index-entry-id" id="index-output-of-assembler-code"></a>

<p>This describes the overall framework of an assembly file.
</p>
<a class="index-entry-id" id="index-default_005ffile_005fstart"></a>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fFILE_005fSTART"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_FILE_START</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fFILE_005fSTART"> &para;</a></span></dt>
<dd><p>Output to <code class="code">asm_out_file</code> any text which the assembler expects to
find at the beginning of a file.  The default behavior is controlled
by two flags, documented below.  Unless your target&rsquo;s assembler is
quite unusual, if you override the default, you should call
<code class="code">default_file_start</code> at some point in your target hook.  This
lets other target files rely on these variables.
</p></dd></dl>

<dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fASM_005fFILE_005fSTART_005fAPP_005fOFF"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_ASM_FILE_START_APP_OFF</strong><a class="copiable-link" href="#index-TARGET_005fASM_005fFILE_005fSTART_005fAPP_005fOFF"> &para;</a></span></dt>
<dd><p>If this flag is true, the text of the macro <code class="code">ASM_APP_OFF</code> will be
printed as the very first line in the assembly file, unless
<samp class="option">-fverbose-asm</samp> is in effect.  (If that macro has been defined
to the empty string, this variable has no effect.)  With the normal
definition of <code class="code">ASM_APP_OFF</code>, the effect is to notify the GNU
assembler that it need not bother stripping comments or extra
whitespace from its input.  This allows it to work a bit faster.
</p>
<p>The default is false.  You should not set it to true unless you have
verified that your port does not generate any extra whitespace or
comments that will cause GAS to issue errors in NO_APP mode.
</p></dd></dl>

<dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fASM_005fFILE_005fSTART_005fFILE_005fDIRECTIVE"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_ASM_FILE_START_FILE_DIRECTIVE</strong><a class="copiable-link" href="#index-TARGET_005fASM_005fFILE_005fSTART_005fFILE_005fDIRECTIVE"> &para;</a></span></dt>
<dd><p>If this flag is true, <code class="code">output_file_directive</code> will be called
for the primary source file, immediately after printing
<code class="code">ASM_APP_OFF</code> (if that is enabled).  Most ELF assemblers expect
this to be done.  The default is false.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fFILE_005fEND"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_FILE_END</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fFILE_005fEND"> &para;</a></span></dt>
<dd><p>Output to <code class="code">asm_out_file</code> any text which the assembler expects
to find at the end of a file.  The default is to output nothing.
</p></dd></dl>

<dl class="first-deftypefn first-deftypefun-alias-first-deftypefn">
<dt class="deftypefn deftypefun-alias-deftypefn" id="index-file_005fend_005findicate_005fexec_005fstack"><span class="category-def">Function: </span><span><code class="def-type">void</code> <strong class="def-name">file_end_indicate_exec_stack</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-file_005fend_005findicate_005fexec_005fstack"> &para;</a></span></dt>
<dd><p>Some systems use a common convention, the &lsquo;<samp class="samp">.note.GNU-stack</samp>&rsquo;
special section, to indicate whether or not an object file relies on
the stack being executable.  If your system uses this convention, you
should define <code class="code">TARGET_ASM_FILE_END</code> to this function.  If you
need to do other things in that hook, have your hook function call
this function.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fLTO_005fSTART"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_LTO_START</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fLTO_005fSTART"> &para;</a></span></dt>
<dd><p>Output to <code class="code">asm_out_file</code> any text which the assembler expects
to find at the start of an LTO section.  The default is to output
nothing.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fLTO_005fEND"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_LTO_END</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fLTO_005fEND"> &para;</a></span></dt>
<dd><p>Output to <code class="code">asm_out_file</code> any text which the assembler expects
to find at the end of an LTO section.  The default is to output
nothing.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fCODE_005fEND"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_CODE_END</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fCODE_005fEND"> &para;</a></span></dt>
<dd><p>Output to <code class="code">asm_out_file</code> any text which is needed before emitting
unwind info and debug info at the end of a file.  Some targets emit
here PIC setup thunks that cannot be emitted at the end of file,
because they couldn&rsquo;t have unwind info then.  The default is to output
nothing.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-ASM_005fCOMMENT_005fSTART"><span class="category-def">Macro: </span><span><strong class="def-name">ASM_COMMENT_START</strong><a class="copiable-link" href="#index-ASM_005fCOMMENT_005fSTART"> &para;</a></span></dt>
<dd><p>A C string constant describing how to begin a comment in the target
assembler language.  The compiler assumes that the comment will end at
the end of the line.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-ASM_005fAPP_005fON"><span class="category-def">Macro: </span><span><strong class="def-name">ASM_APP_ON</strong><a class="copiable-link" href="#index-ASM_005fAPP_005fON"> &para;</a></span></dt>
<dd><p>A C string constant for text to be output before each <code class="code">asm</code>
statement or group of consecutive ones.  Normally this is
<code class="code">&quot;#APP&quot;</code>, which is a comment that has no effect on most
assemblers but tells the GNU assembler that it must check the lines
that follow for all valid assembler constructs.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-ASM_005fAPP_005fOFF"><span class="category-def">Macro: </span><span><strong class="def-name">ASM_APP_OFF</strong><a class="copiable-link" href="#index-ASM_005fAPP_005fOFF"> &para;</a></span></dt>
<dd><p>A C string constant for text to be output after each <code class="code">asm</code>
statement or group of consecutive ones.  Normally this is
<code class="code">&quot;#NO_APP&quot;</code>, which tells the GNU assembler to resume making the
time-saving assumptions that are valid for ordinary compiler output.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-ASM_005fOUTPUT_005fSOURCE_005fFILENAME"><span class="category-def">Macro: </span><span><strong class="def-name">ASM_OUTPUT_SOURCE_FILENAME</strong> <var class="def-var-arguments">(<var class="var">stream</var>, <var class="var">name</var>)</var><a class="copiable-link" href="#index-ASM_005fOUTPUT_005fSOURCE_005fFILENAME"> &para;</a></span></dt>
<dd><p>A C statement to output COFF information or DWARF debugging information
which indicates that filename <var class="var">name</var> is the current source file to
the stdio stream <var class="var">stream</var>.
</p>
<p>This macro need not be defined if the standard form of output
for the file format in use is appropriate.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fOUTPUT_005fSOURCE_005fFILENAME"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_OUTPUT_SOURCE_FILENAME</strong> <code class="def-code-arguments">(FILE *<var class="var">file</var>, const char *<var class="var">name</var>)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fOUTPUT_005fSOURCE_005fFILENAME"> &para;</a></span></dt>
<dd><p>Output DWARF debugging information which indicates that filename
<var class="var">name</var> is the current source file to the stdio stream <var class="var">file</var>.
</p>
<p>This target hook need not be defined if the standard form of output
for the file format in use is appropriate.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fOUTPUT_005fIDENT"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_OUTPUT_IDENT</strong> <code class="def-code-arguments">(const char *<var class="var">name</var>)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fOUTPUT_005fIDENT"> &para;</a></span></dt>
<dd><p>Output a string based on <var class="var">name</var>, suitable for the &lsquo;<samp class="samp">#ident</samp>&rsquo;
directive, or the equivalent directive or pragma in non-C-family languages.
If this hook is not defined, nothing is output for the &lsquo;<samp class="samp">#ident</samp>&rsquo;
directive.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-OUTPUT_005fQUOTED_005fSTRING"><span class="category-def">Macro: </span><span><strong class="def-name">OUTPUT_QUOTED_STRING</strong> <var class="def-var-arguments">(<var class="var">stream</var>, <var class="var">string</var>)</var><a class="copiable-link" href="#index-OUTPUT_005fQUOTED_005fSTRING"> &para;</a></span></dt>
<dd><p>A C statement to output the string <var class="var">string</var> to the stdio stream
<var class="var">stream</var>.  If you do not call the function <code class="code">output_quoted_string</code>
in your config files, GCC will only call it to output filenames to
the assembler source.  So you can use it to canonicalize the format
of the filename using this macro.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fNAMED_005fSECTION"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_NAMED_SECTION</strong> <code class="def-code-arguments">(const char *<var class="var">name</var>, unsigned int <var class="var">flags</var>, tree <var class="var">decl</var>)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fNAMED_005fSECTION"> &para;</a></span></dt>
<dd><p>Output assembly directives to switch to section <var class="var">name</var>.  The section
should have attributes as specified by <var class="var">flags</var>, which is a bit mask
of the <code class="code">SECTION_*</code> flags defined in <samp class="file">output.h</samp>.  If <var class="var">decl</var>
is non-NULL, it is the <code class="code">VAR_DECL</code> or <code class="code">FUNCTION_DECL</code> with which
this section is associated.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fELF_005fFLAGS_005fNUMERIC"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_ASM_ELF_FLAGS_NUMERIC</strong> <code class="def-code-arguments">(unsigned int <var class="var">flags</var>, unsigned int *<var class="var">num</var>)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fELF_005fFLAGS_005fNUMERIC"> &para;</a></span></dt>
<dd><p>This hook can be used to encode ELF section flags for which no letter
code has been defined in the assembler.  It is called by
<code class="code">default_asm_named_section</code> whenever the section flags need to be
emitted in the assembler output.  If the hook returns true, then the
numerical value for ELF section flags should be calculated from
<var class="var">flags</var> and saved in <var class="var">*num</var>; the value is printed out instead of the
normal sequence of letter codes.  If the hook is not defined, or if it
returns false, then <var class="var">num</var> is ignored and the traditional letter sequence
is emitted.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fFUNCTION_005fSECTION"><span class="category-def">Target Hook: </span><span><code class="def-type">section *</code> <strong class="def-name">TARGET_ASM_FUNCTION_SECTION</strong> <code class="def-code-arguments">(tree <var class="var">decl</var>, enum node_frequency <var class="var">freq</var>, bool <var class="var">startup</var>, bool <var class="var">exit</var>)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fFUNCTION_005fSECTION"> &para;</a></span></dt>
<dd><p>Return preferred text (sub)section for function <var class="var">decl</var>.
Main purpose of this function is to separate cold, normal and hot
functions. <var class="var">startup</var> is true when function is known to be used only
at startup (from static constructors or it is <code class="code">main()</code>).
<var class="var">exit</var> is true when function is known to be used only at exit
(from static destructors).
Return NULL if function should go to default text section.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fFUNCTION_005fSWITCHED_005fTEXT_005fSECTIONS"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_FUNCTION_SWITCHED_TEXT_SECTIONS</strong> <code class="def-code-arguments">(FILE *<var class="var">file</var>, tree <var class="var">decl</var>, bool <var class="var">new_is_cold</var>)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fFUNCTION_005fSWITCHED_005fTEXT_005fSECTIONS"> &para;</a></span></dt>
<dd><p>Used by the target to emit any assembler directives or additional
labels needed when a function is partitioned between different
sections.  Output should be written to <var class="var">file</var>.  The function
decl is available as <var class="var">decl</var> and the new section is &lsquo;cold&rsquo; if
<var class="var">new_is_cold</var> is <code class="code">true</code>.
</p></dd></dl>

<dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fHAVE_005fNAMED_005fSECTIONS"><span class="category-def">Common Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_HAVE_NAMED_SECTIONS</strong><a class="copiable-link" href="#index-TARGET_005fHAVE_005fNAMED_005fSECTIONS"> &para;</a></span></dt>
<dd><p>This flag is true if the target supports <code class="code">TARGET_ASM_NAMED_SECTION</code>.
It must not be modified by command-line option processing.
</p></dd></dl>

<a class="anchor" id="TARGET_005fHAVE_005fSWITCHABLE_005fBSS_005fSECTIONS"></a><dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fHAVE_005fSWITCHABLE_005fBSS_005fSECTIONS"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_HAVE_SWITCHABLE_BSS_SECTIONS</strong><a class="copiable-link" href="#index-TARGET_005fHAVE_005fSWITCHABLE_005fBSS_005fSECTIONS"> &para;</a></span></dt>
<dd><p>This flag is true if we can create zeroed data by switching to a BSS
section and then using <code class="code">ASM_OUTPUT_SKIP</code> to allocate the space.
This is true on most ELF targets.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fSECTION_005fTYPE_005fFLAGS"><span class="category-def">Target Hook: </span><span><code class="def-type">unsigned int</code> <strong class="def-name">TARGET_SECTION_TYPE_FLAGS</strong> <code class="def-code-arguments">(tree <var class="var">decl</var>, const char *<var class="var">name</var>, int <var class="var">reloc</var>)</code><a class="copiable-link" href="#index-TARGET_005fSECTION_005fTYPE_005fFLAGS"> &para;</a></span></dt>
<dd><p>Choose a set of section attributes for use by <code class="code">TARGET_ASM_NAMED_SECTION</code>
based on a variable or function decl, a section name, and whether or not the
declaration&rsquo;s initializer may contain runtime relocations.  <var class="var">decl</var> may be
null, in which case read-write data should be assumed.
</p>
<p>The default version of this function handles choosing code vs data,
read-only vs read-write data, and <code class="code">flag_pic</code>.  You should only
need to override this if your target has special flags that might be
set via <code class="code">__attribute__</code>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fASM_005fRECORD_005fGCC_005fSWITCHES"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_ASM_RECORD_GCC_SWITCHES</strong> <code class="def-code-arguments">(const char *<var class="var"></var>)</code><a class="copiable-link" href="#index-TARGET_005fASM_005fRECORD_005fGCC_005fSWITCHES"> &para;</a></span></dt>
<dd><p>Provides the target with the ability to record the gcc command line
switches provided as argument.
</p>
<p>By default this hook is set to NULL, but an example implementation is
provided for ELF based targets.  Called <var class="var">elf_record_gcc_switches</var>,
it records the switches as ASCII text inside a new, string mergeable
section in the assembler output file.  The name of the new section is
provided by the <code class="code">TARGET_ASM_RECORD_GCC_SWITCHES_SECTION</code> target
hook.
</p></dd></dl>

<dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fASM_005fRECORD_005fGCC_005fSWITCHES_005fSECTION"><span class="category-def">Target Hook: </span><span><code class="def-type">const char *</code> <strong class="def-name">TARGET_ASM_RECORD_GCC_SWITCHES_SECTION</strong><a class="copiable-link" href="#index-TARGET_005fASM_005fRECORD_005fGCC_005fSWITCHES_005fSECTION"> &para;</a></span></dt>
<dd><p>This is the name of the section that will be created by the example
ELF implementation of the <code class="code">TARGET_ASM_RECORD_GCC_SWITCHES</code> target
hook.
</p></dd></dl>

</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Data-Output.html">Output of Data</a>, Up: <a href="Assembler-Format.html">Defining the Output Assembler Language</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
